PAN to CIN Details API

This document outlines the details of the PAN to CIN Details API.

API Description

Objective

The PAN to CIN Details API accepts a PAN (Permanent Account Number) as input and retrieves the corresponding Corporate Identification Number (CIN) details.

Input	Output
The PAN and consent	Details about: CIN Company name State of incorporation Incorporation date Company status The complete list of output fields is available in the Success Response Details section

API URL

https://ind-engine.thomas.hyperverge.co/v1/panToCinDetails

API Endpoint

panToCinDetails

Overview

The API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should send all data in JSON format through a POST request. This API retrieves verified CIN Details using PAN Number.

Authentication

You need a unique pair of application ID ( appId ) and application key (appKey) from HyperVerge to verify your identity for accessing the API.

API Request Details

Method - POST

Headers

Parameter	Mandatory or Optional	Description	Valid Values
content-type	Mandatory	This parameter defines the media type for the request payload.	application/json
appId	Mandatory	The application ID shared by HyperVerge	Not Applicable - this is a unique value
appKey	Mandatory	The application key shared by HyperVerge	Not Applicable - this is a unique value
transactionId	Mandatory	The unique ID for the customer journey.	Not Applicable - this is a unique value related to a transaction in your application

Input

The following table provides the details of the parameters required for the API's request body:

Parameter	Mandatory or Optional	Description	Allowed Values	Default Value
pan	Mandatory	The Permanent Account Number (PAN)	A 10-character alphanumeric code	Not Applicable
consent	Mandatory	The consent provided by the user to retrieve CIN details	Y or N	Not Applicable

Request

The following code snippet demonstrates a standard curl request for the API:

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/panToCinDetails' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "pan": "<Enter_the_PAN>",
    "consent": "<Enter_Y_or_N>"
}'

Success Response

The following code snippet demonstrates a success response from the API:

{
  "status": "success",
  "statusCode": 200,
  "result": {
    "cin": "<Corporate_Identification_Number>",
    "company": "<Company_Name>",
    "state": "<State_Of_Incorporation>",
    "incorporation_date": "<Incorporation_Date_In_DD/MM/YYYY_Format>",
    "company_status": "<Company_Status>"
  },
  "metadata": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Success Response Details

The following table outlines the details of the success response from the API:

Parameter	Type	Description
status	string	The status of the API request indicating success or failure
statusCode	integer	The HTTP status code returned for the API request
result	object	The main response object containing all CIN-related information
cin	string	The Corporate Identification Number (CIN) assigned to the company
company	string	The registered legal name of the company
state	string	The state in which the company is registered
incorporation_date	string	The date on which the company was incorporated in DD/MM/YYYY format
company_status	string	The current operational status of the company (e.g., Active, Inactive)
metadata	object	Contains metadata information about the API request
requestId	string	The unique identifier for the API request
transactionId	string	The transaction ID associated with the API request

Error Responses

PAN Undefined

{
  "message": "Input Validation Error: requires property \"pan\"",
  "statusCode": 400,
  "status": "failure"
}

Consent Undefined

{
  "message": "Input Validation Error: requires property \"consent\"",
  "statusCode": 400,
  "status": "failure"
}

PAN Empty

{
  "status": "failure",
  "statusCode": 400,
  "error": "PAN is required",
  "metadata": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Unsupported PAN Type

{
  "status": "failure",
  "statusCode": 400,
  "error": "Unsupported PAN type",
  "metadata": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Consent Empty

{
  "message": "Input Validation Error: consent is not one of enum values: Y,N",
  "statusCode": 400,
  "status": "failure"
}

Consent Invalid

{
  "status": "failure",
  "statusCode": 400,
  "error": "consent is invalid",
  "metadata": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Invalid PAN Format

{
  "status": "failure",
  "statusCode": 400,
  "error": "Invalid PAN format",
  "metadata": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Record Not Found

{
  "status": "failure",
  "statusCode": 404,
  "error": "No record found",
  "metadata": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Inactive PAN

{
  "status": "failure",
  "statusCode": 422,
  "error": "Inactive PAN",
  "metadata": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Invalid Credentials

{
  "message": "Missing/Invalid credentials",
  "statusCode": 401,
  "status": "failure"
}

Invalid Authentication Key

{
  "status": "failure",
  "statusCode": 401,
  "error": "Authkey is invalid",
  "metadata": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Error Response Details

A failure or error response contains a failure status with a relevant status code and error message.
The following table lists all error responses:

Status Code	Error Message	Error Description	Error Resolution
400	Input Validation Error: requires property "pan"	The PAN field is missing in the request payload	Include the pan field in the request body with a valid PAN value
400	Input Validation Error: requires property "consent"	The consent field is missing in the request payload	Include the consent field in the request body with a value of Y or N
400	PAN is required	The PAN field is present but empty	Provide a valid PAN value in the pan field
400	Unsupported PAN type	The PAN type is not supported for this API	Ensure the PAN belongs to a company entity type that is supported by this API
400	Input Validation Error: consent is not one of enum values: Y,N	The consent value is empty or not among allowed values	Set the consent field to either Y or N
400	consent is invalid	The consent value is invalid (e.g., N)	Set the consent field to Y to proceed with the API request
400	Invalid PAN format	The PAN does not match the required PAN format	Verify the PAN format is correct (10-character alphanumeric code) and try again
401	Missing/Invalid credentials	The request is either missing the mandatory appId and appKey combination or has invalid values	Verify and provide valid appId and appKey credentials
401	Authkey is invalid	The provided authentication key is invalid or expired	Verify the authentication key is correct and has not expired. Contact HyperVerge support if needed
404	No record found	The provided PAN does not exist in the source system	Verify the PAN is correct and exists in the system. Ensure the PAN is associated with a company entity
422	Inactive PAN	The PAN exists but is marked inactive	The PAN is inactive and cannot be used for this operation. Use an active PAN or contact the company for updated information
500	Internal Server Error	An internal server error occurred while processing the request	Check the request headers or contact the HyperVerge team for resolution
503	External source downtime	The upstream source is unavailable or down	Retry the request after some time or contact the HyperVerge team if the issue persists